Creating
a Cabinet Callback Routine
Because the
Setup API does not supply a default cabinet callback routine, you need to
supply a routine. The callback routine that the SetupIterateCabinet function requires must
have the same form as those pointed to by SP_FILE_CALLBACK.
Following is
the syntax that SetupIterateCabinet uses to send a notification to the
callback routine.
MsgHandler(
//the specified callback routine
Context, //context used by the callback routine
Notification, //cabinet notification
Param1, //additional notification information
Param2 //additional
notification information
);
The Context
parameter is a void pointer to a context variable or structure that can be used
by the callback routine to store information that needs to persist between
subsequent calls to the callback routine.
This context s implementation is specified by the callback routine,
and it is never referenced or altered by SetupIterateCabinet.
The Notification
parameter is an unsigned integer and will be one of the following values.
|
SPFILENOTIFY_FILEEXTRACTED |
The file
has been extracted from the cabinet. |
|
SPFILENOTIFY_FILEINCABINET |
A file is
encountered in the cabinet. |
|
SPFILENOTIFY_NEEDNEWCABINET |
The current
file is continued in the next cabinet. |
The final two
parameters, Param1 and Param2, are also unsigned integers and
contain additional information relevant to the notification. For more
information about the notifications sent by SetupIterateCabinet, see Cabinet
File Notifications.
A
SP_FILE_NOTIFY_CALLBACK routine returns an unsigned integer. The cabinet callback
routine should return one of the following values depending on the
notification.
For the
SPFILENOTIFY_FILEINCABINET notification, SetupIterateCabinet expects one
of the following values to be returned by the callback routine.
|
FILEOP_ABORT |
Abort
cabinet processing. |
|
FILEOP_DOIT |
Extract the
current file. |
|
FILEOP_SKIP |
Skip the
current file. |
For
SPFILENOTIFY_NEEDNEWCABINET and SPFILENOTIFY_FILEEXTRACTED notifications, SetupIterateCabient
expects one of the following values to be returned by the callback routine.
|
NO_ERROR |
No error
was encountered, continue processing the cabinet. |
|
ERROR_XXX |
An error of
the specified type occurred. The SetupIterateCabinet function will
return FALSE, and the specified error code will be returned by a call to GetLastError. |
If the
callback routine returns FILEOP_DOIT, the routine must also provide a full
target path. For more information see SPFILENOTIFY_FILEINCABINET.